Documentation

Library

essentials

Version

2.1.0

This section contains the Seadex essentials library documentation including the API reference.

Building essentials

This section provides you with instructions on how to build essentials in your environment.

Getting the source

  • Download the essentials package including the C++ source code from the essentials homepage.

  • Unzip the source package into a directory of your choice (this is referred to as $EDIR in the rest of the documentation). You can use 7-Zip or a similar tool for this task.

Building

These building options are available:

  • Microsoft Visual Studio - Description of how to build essentials with Microsoft Visual Studio and the Microsoft Visual Studio Compiler (using the provided solution and projects).

  • CMake - Description page for building essentials using CMake for Linux and Windows (Visual Studio/MSBuild).

Other compilers and platforms

Building for Linux with gcc is supported out of the box. For other compilers and/or platforms you can just adopt the CMake files.

Alternatively, you can quite easily set up your build. All you need to build essentials with a different compiler suite and/or on a different platform is C++17 support. Just take the essentials source code and set up a library project according to the procedures necessary for your platform.

You can also contact us to get a quote for commercial support for porting essentials to your platform!

If you run into compiler/build problems in your environment (especially compiler errors or warnings), please contact us. We then will try to resolve these issues.

Microsoft Visual Studio

2019

For Visual Studio 2019 a ready-to-use solution is provided. It contains:

  • essentials - source code of the essentials library

  • essentials_unit_tests - source code of the unit tests

  • examples - projects using and demonstrating some of the features of essentials

  • bug_reproductions - projects where bugs are reproduced

  • build - a folder containing the property sheets for the projects

  • essentials.sln - the solution file that contains the projects mentioned above

  • license file

  • docs - a folder containing the documentation

Use of Conan

The essentials library can use Conan to get its dependencies (see the Dependencies)

After the build, the essentials library can be integrated into your projects.

CMake

The build with CMake is currently tested for Linux (Debian, gcc) and Windows (Microsoft Visual Studio).

The following were used:

  • Debian 11

  • gcc 10.2.1

The CMakeFileLists.txt files are located in the solution directory, the essentials project directory, the examples directory, and the directory of the unit tests project.

Generating with CMake and Conan
Note
 The following commands require Conan version 2.0.
Linux

In a terminal go to the directory into which you extracted essentials and run the following commands:

conan install . -g CMakeToolchain --profile=release --build=missing -of cmake

cd cmake

cmake .. -G "Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DSPDLOG_FMT_EXTERNAL=ON -DCMAKE_BUILD_TYPE=Release -DESS_BUILD_UNIT_TESTS=ON

cmake --build --preset conan-release
Note
 Options (e.g. architecture) are used from the Conan profile.
Windows

In a terminal go to the directory into which you extracted essentials and run the following commands:

conan install . -g CMakeToolchain --profile=release --build=missing

cmake . -G "Visual Studio 16 2019" -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DSPDLOG_FMT_EXTERNAL=ON -DESS_BUILD_UNIT_TESTS=ON

cmake --build --preset conan-release
Note
 Options like architecture, Visual Studio version (generator), etc…​ are used from Conan profiles.

Release/Debug

Choosing between release and debug builds is done via Conan profiles and presets.

Preprocessor definitions

Using essentials' preprocessor definitions with CMake is also possible by passing them as parameters in the console/terminal.

Definition Description

CPP_VERSION=[VALUE]

Sets the standard for the C++ compiler. When it is not used, C++11 will be used.

ESS_USE_NULL_LOGGER=[ON]

When ESS_USE_NULL_LOGGER is defined (no matter what value) a null logger will be used. This means, no logging.

Build options

The essentials build can be customized using the following options:

ESS_BUILD_UNIT_TESTS=[OFF] When ESS_BUILD_UNIT_TESTS is defined, the unit tests project will be built as well. By default it is not defined and therefore, not built.

FMT_LIB_INCLUDE=[VALUE]

FMT_LIB=[VALUE]

SPDLOG_LIB_INCLUDE=[VALUE]

SPDLOG_LIB=[VALUE]

To use fmt and spdlog libraries from the user location, all four variables must be used at the same time with the correct paths. For the libs, the library is specified as well (e.g. "…​/fmt/lib/fmt.lib").

GTEST_LIB_INCLUDE=[VALUE]

GTEST_LIB=[VALUE]

To build the unit tests project without Conan, the Google test library reference must be used.

Dependencies

The essentials library starting with version 2.1 has the following dependencies:

  • gtest 1.13.0

  • spdlog 1.11.0

  • fmt 9.1.0

These dependencies can be provided using Conan (see Use of Conan).

The gtest library is used for unit tests only.

Features

Features of the library.

Log

The essentials library supports logging.

Log macros

There are 3 macros used to create logs:

  • SXE_LOG taking parameters:

    • log-level

    • message

    • [optional] parameter(s)

  • SXE_LOG_LOCATED taking parameters:

    • log-level

    • file

    • line

    • message

    • [optional] parameter(s)

  • SXE_LOG_HEX taking parameters:

    • log-level

    • object

    • title

Log-levels

The following log levels are supported:

  • LL_TRACE

  • LL_DEBUG

  • LL_INFO

  • LL_WARN

  • LL_ERROR

  • LL_FATAL

  • LL_OFF

Example

There is an example project (logger_example) showing how to initialize and use the logger in the essentials library.

A short example of initializing and using the logger:

auto& logger = sxe::logger::get_instance();
sxe::logger_manager::get_instance().set_logger( logger );
logger.set_log_level( LL_ERROR );
logger.add_std_out_sink();
logger.add_file_sink( "log.log", 1, 1 * 1024 * 1024 );

SXE_LOG( LL_TRACE, "Hello {}!", "John Doe" );

Execution context

A class that runs a function in a different thread.

Example

An example can be found in the project 'context_example'.

Enhanced enum

The essentials library provides macros to create enhanced enums. The macros will create an enum structures that provide more functionality than a classic enum structure.

Macros

  • SXE_ENHANCED_ENUM with up to 50 enumerators.

  • SXE_ENHANCED_ENUM_NUMERIC with up to 50 enumerators with associated numeric values.

Exception

Exception macros

The following macros can be used within the essentials library to create exception classes:

  • SXE_EXCEPTION creates an exception class inheriting std::exception with the given name. It also supports creating messages with placeholders by calling fmt::format.

  • SXE_EXCEPTION_WITH_BASE creates an exception class inheriting the given base class with the given name. It also supports creating messages with placeholders by calling fmt::format.

  • SXE_EXCEPTION_WITH_CODE_IN_NAMESPACE creates an exception class inheriting std::exception with the given name. It also supports creating messages with placeholders by calling fmt::format. It provides an error code as well.

  • SXE_EXCEPTION_WITH_CODE creates an exception class inheriting std::exception with the given name. It also supports creating messages with placeholders by calling fmt::format. It provides an error code as well.

File

The essentials library provides some basic file content manipulating functionality.

The provided functions are:

  • get the content of a file as a string

  • get the content of a file as bytes

  • write bytes to a file

  • write a string to a file

Math

Provides a single function for now:

  • round rounds a double value to the given precision.

No copy macro

  • SXE_NO_COPY deletes the copy constructor and assignment operator of the given class.

  • SXE_NO_ASSIGNMENT_OPERATOR deletes the assignment operator of the given class.

String

Provides the following string helper functionality:

  • replace all

  • split

Type wrapper

  • SXE_CREATE_TYPE_IN_NAMESPACE

  • SXE_CREATE_TYPE_WITH_STR_FORMATTER_IN_NAMESPACE

Uri

Provides uri functionality.

Reference

This section contains the reference documentation for the C++ code. The types (classes, enums, …​), functions, and macros that the “essentials” library provides are explained here.

MIT License

Copyright (c) 2017-, Seadex GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Downloads

Download the latest version of the essentials library here.

For older versions, you shall check on the essentials' GitHub.

Changelog

Versions

All notable changes to this project are documented on this page.

[2.0.0]

The library is now licensed under the MIT license.

Added

  • logging

  • threading context

  • bytes helper functions

  • string conversion functions

  • helper functions for file to string and file to bytes and vice versa

  • data type wrapper macro

Changed

  • removed support for C++03

  • removed Boost library dependencies

  • integrated fmt and spdlog libraries

  • improved uri class

  • improved data type conversions

[1.3.2]

Added

  • SX_UNUSED_VARIABLE macro for suppressing warnings for an unreferenced variable.

  • backward compatibility for macros Y_NO_STD_MAKE_UNIQUE, Y_CPP03_BOOST, Y_UNIQUE_PTR, Y_MAKE_UNIQUE, Y_MAKE_SHARED, Y_UNUSED_PARAMETER

Changed

  • CMake: use external CMakeHelpers files

  • CMake: refactoring of build scripts

Fixed

  • missing boost namespace in sxprintf

[1.3.1]

Changed

  • CMake file improvements: Set C++-standard version (when using gcc) using CPP_VERSION with values '03' for C++03, '14' for C++14. Default is C++11.

[1.3.0]

[1.2.0]

Changed

  • internal structure update

  • printf code improvements

  • helper macro extended up to 15 parameters

[1.1.0]

Added

  • Support for Visual Studio 2017 builds

  • conversion functions: to_lower and to_upper

  • added uri class

[1.0.1]

Changed

  • macro helpers improved to count up to 15 parameters

  • essentials file structure refactoring. All source files are now located in the 'source' folder, the header files for compatibility are located in the 'include/essentials/compatibility' folder and other header files are located in the 'include/essentials' folder.

[1.0.0]

  • The very first released version of essentials

Contact & support

Your feedback is very important to and for us!

In case you have questions, suggestions, if you want to file a bug report, or if we can assist you in any other way please send us an email to essentials@seadex.de.

Also, we are very glad if you Show your appreciation!

Commercial support

Seadex GmbH from Trossingen, Germany can provide you with commercial support.

Support is available in the form of (but not limited to) the development of specific tools for your environment, custom development within essentials, consulting, or training.

Also, Seadex can support you with additional developers.

Please contact us if you have a question or require a quote.

Show your appreciation

If you like essentials and find it useful, we would be very happy if you’d show your appreciation in one way or the other. It helps us to attract more attention to essentials. The more attention it gets the more feedback and input we get. And that is the knowledge we need to improve essentials further.

There are multiple ways to show your appreciation:

Star essentials on GitHub

Contact us (via Contact & support) and allow us to feature you (or your company) as a reference user.